BCI NET 2/BCI NET 2.iso/archives/utilities/shell/vector11.lha/man/vector.man

Text File | 1994-11-18 | 12.3 KB | 323 lines

VECTOR            SUPERUSER COMMANDS            17-Nov-1994


NAME
    vector - file ratio/validating system for AXsh

SYNOPSIS
    vector [ check | dl | stat | ul ]
    vector [ award <user> | init | new | scan | stat <user>]
        (superuser only)

DESCRIPTION
    Vector is a utility that provides a way of implementing ratios and
    conviniently validating uploads for AXsh.  The AXsh/xpr/ffe trio
    has no ratio system at all, which may cause problems for systems
    that are open to the public.  Also, uploads must be handled manually
    by first creating a description, then changing the file protections
    so the file is visible, and then moving it manually.  Vector,
    along with its companion utility AddDesc, handles descriptions,
    takes care of ratios automatically, prompts the user for
    descriptions and file placement, and makes validating much more
    convenient.

WARNING
    This document is intended for the systen administrator only, since
    to the normal user Vector will be largely transparent and/or obvious.

    Also, Vector v1.1 is, as a colleague said, "very cool, but ugly."
    This is true: I have concentrated on getting the core of the program
    working before the public opening of my system, and not on the
    frills.  As a direct corollary, only features that I find useful
    exist.  Future versions will feature much more: if you have ideas,
    please mail me.

    That said...

REQUIREMENTS
    Vector needs KS 2.0 or better and the PIPE: device mounted.
    And an AXsh BBS might be a good idea too.  =)  Everything else
    necessary is included with the archive, I hope...

INSTALLATION
    Vector needs configuration since the file configuration of each
    BBS is quite different.  The simplest thing to do is to unpack
    the Vector archive in your AXsh: directory, and then edit the
    following files as instructed.

    The most crucial file is rc.vector.  You must edit the following
    parameters (remember the / or : after _all_ directories!):

    %vectorpath:    This is where Vector stores its data files.  Default
            is "AXsh:etc/vector/".  At the moment there are
            only a few files, so you might wish to use just
                        "AXsh:etc/".

    %uploadpath:    This is temporary directory where uploads are _first_
            sent.  This directory must only contain the uploads
            of the current upload session!  Default is
            "Storage:Temp/", you will almost certainly need to
            change this.  Note that you must insure that your
            xprotos.tab paths match this.  Placing this
            in physical media (ie. not RAM) is recommended,
            in case the computer crashes or something...

    %initbyte:    This is the amount of bytes of credits given to
            each user the first time they download or upload.
            Defaults to 1000000 bytes (1MB).

    %uploadtype:    This defines the types of uploads available on your
            system.  The format is <name> <directory> <minimum
            accesslevel>.  For example:

            General      Storage:Uploads/   normal

            Would create a category named "General", whose
            uploads are moved to Storage:Uploads/, and
            which requires an accesslevel of "normal" or better.
            The user will select among the types available.
            The first blank line terminates the type listing.
            If the above makes no sense, look at the included
            rc.vector file.

    %filetype:    These are the types of files the sysop gets to
            place files in.  The format is <name> <path>
            <ratio>, where name and path are same as before
            and ratio is an integer, ie. 3 would award
            3 credits for each byte uploaded.  Example:

            Modules   Storage:Modules/  5

            Would create a category named "Modules", whose
            files are moved to Storage:Modules/, and for which
            a 1:5 ratio is in place.  The first blank line
            terminates the type listing.  Again, if the above
            makes no sense, look at the included rc.vector file.

    Once this is done, create the required directories and remember to
    adjust etc/xprotos.tab as needed.  Then add bin/vector and
    bin/adddesc to your AXsh:etc/rc.  Finally, type "vector init",
    and Vector will proceed to create records from xpr.log.

    That installs Vector itself, now you'll have to set up your BBS so
    that Vector is useful.  The scripts directory contains three scripts:
    upload, ffe.axsh, and ffe.dos.  They attempt to    be universal and
    should work for all systems.  Place these in a convinient
        world-readable place, I have a public /extern directory for scripts.
    Add the following to your etc/GlobalLogin:

        alias upload "execute /extern/upload"
        alias "xpr r z" "execute /extern/upload"
        alias ffe "execute /extern/ffe.axsh"

    In Matrix, change the entries for uploading and FFE respectively to
    "execute AXsh:extern/upload" and "execute AXsh:extern/ffe.dos".
    Two separate FFE scripts are needed since AXsh and ADos handle
    if-statements differently.

    One last thing is needed: depending on the size of your xpr.log
    and the speed of your HD, you'll need to add the line

        vector >>AXsh:etc/adm/vector.log dl

    to either your AXsh launch script to be executed after the user
    logs off or into a nightly cleanup script.  On my '030/25 machine
    with a Quantum HD, the scan speed is approximately 50K/second,
        ie. a 500K xpr.log is scanned in approx. 10 seconds.  You may
        also wish to trim vector.log regularly or it will grow to an
        unmanageable size.

    Now uploads and downloads are under Vector, and all you have to do
    is type "vector scan" from your root account every now and then and
    validate your uploads.

USER COMMANDS
    Normal users can perform four commands, given as arguments to
    Vector:

    check    This checks if a user has credits left, and if not
        returns with return code 5 (WARN).  Useful for scripts.

    dl    This scans for new downloads and substracts credits.
        This should be loaded after FFE and/or after the user logs
        off, but may be performed nightly if xpr.log's length
        makes it prohibitively slow.  Vector dl's output goes to
        stdout but the format is intended for logging, so redirection
        is possible and recommended.

    stat    This tells the number of credits the user has left.

    ul    This scans for new uploads, asks for descriptions,
        deprotects, touches (updates the datestamp to present) and
        moves them.  This should be a part of an uploading script
        such as the included "ulscript".

SUPERUSER COMMANDS
    There are an extra five commands available to superusers:

    award    This will award extra credits to a user.  Credits can also
        be taken away by awarding negative bytes.

    init    This will initialize Vector's records completely, rereading
        everything from xpr.log.  You will be asked for a default
        ratio, which need not match the rc.vector default.

    new    This lists all new uploads and their descriptions since
        the last 'Vector scan' command.

    scan    The most important superuser command, this scans for new
        uploads and lets the sysop validate them.  For each
        file, the sysop gets something like the following:

        Uploaded by elvis: "pelvis.gif", 123456 bytes
        Description:
        It's my pelvis in action.
        (V)alidate, (Q)uick Validate, (D)elete, (I)gnore or (A)bort?

        V)alidate will ask you if you want to rewrite the description
        or rename the file (and its description along with it,
        naturally).  Then, you'll be presented with a list
        of possible filetypes, plus the extra selections A B C D
        that let you manipulate the file in any way you want.
        Once you've made your selection, the files will be moved
        and credits awarded.

        Q)uick Validate will leave description and filename
        untouched and just ask you to pick a category.

        D)elete will delete the file and its description, with no
        credits awarded.

        I)gnore will mark the file as scanned and go to the next
        file, with no credits awarded.

        A)bort will quit Vector and leave all uploads on the
        list, including ones before the abort, to be checked next
        time.

    stat    Superusers may also specify the name of a user for stat.

SECURITY
    Vector has rather poor security when it comes to avoiding
    ripoff attempts, largely due to the fact that it's an add-on
    and not an integral part of xpr.  Briefly, without giving too much
    detail to would-be hackers:

    - credits are modified only after the download itself
    - Vector's checking cannot anticipate the size of the download(s)
      that follow
    - Avoiding a Vector check from the shell is trivial

    In other words, Vector will not prevent a user who will leech
    like hell once and never call back, or a shell-aware user
    who will return to leech.  But as my excuse, I must say that
    it's FFE's fault, not Vector's.  =)

    To stop such evil behavior, take the following draconian measures:

    - No shell access, or at least no access to ffe/xpr from shell.
    - Run a "vector dl" as a daemon, maybe as often as every half hour.
          Make the script kick the user out if the user goes over his limit.

    On my system I have not found such measures to be necessary,
    but to each his own...

PROGRAMMERS
    The SAS/C v6.5 source code to both Vector and AddDesc has been
    included, so you hackers out there can cook up your own fixes.
    To compile, just CD to the src directory and type "smake".
    If you come up with interesting modifications or find bugs, please
    mail me instead of releasing modified versions.

FUTURE FEATURES
    There are so many things I'm planning for Vector that it's not
    funny...
    - Unlimited ratio for some users
    - A special version of FFE for Vector
    - Much better validating menu with more things to fiddle with
      (can you get vaguer than that?)
    - Ability to view files and archives from within Vector
    - Ability to leave files for later validation while validating others
    - Replacing external protect/touch/move with internal code
    - Configurability everywhere

AUTHOR           _
    Jani "Guru Gnosis Sahib" Poijärvi
    Internet: [e-mail]
    BBS: Brahman, [phone], 16800 24h/7d
             (official Vector support site)

FILES
    c:protect
    /bin/adddesc
    /bin/editor (or as defined in $visual)
    /bin/move
    /bin/touch
    /etc/rc.vector
    /etc/xprotos.tab
    /etc/adm/vector.log
    /etc/adm/xpr.log
    /etc/vector/.lastcheck
    /etc/vector/.newul
    /etc/vector/.ratio

SEE ALSO
    adddesc
    morestat
    xpr

NOTES
    Move is a part of the AmigaDOS Replacement Project (ARP) v1.3
    and is freely distributable.  Unlike some of ARP, it works quite
    nicely with KS v2/v3, but it does require the arp.library.

    Touch is by Matthew Dillon, I assume it's freely distributable
    since DICE's docs never mention it...

    It is theoretically possible to use Vector without AXsh...
    however, I wouldn't recommend it, since you'd still have to use
    xpr and Vector is largely pointless without FFE.

    The separate program "MoreStat" generates statistics with Vector's
    ratio information, look for it at a good AXsh BBS near you.  =)

RESTRICTIONS
    Vector has an arbitrary limit of 250 users with file records.
    If this is too limiting, change the #define USER_MAX to something
    bigger and recompile.  Mind you, on my system less than half the
    users have Vector file records, so 250 should suffice for a while.
    If the limit is passed (warnings will appear in the log), you
    can purge dead users from .ratio manually; I may write a program
    to do this automatically someday.

    Vector makes a number of possibly dangerous assumptions:
    - The first two lines of xpr.log are headers and can be skipped over.
    - The file name, location or size does not change between uploading
      and the sysop validating it.

BUGS
    On rare occasions, Vector will for some unknown reason write
    two copies of its .ratio file in a row, resulting in all
    records being duplicated and all sorts of weird things happening.
    I have never been able to make this happen under "laboratory"
    conditions and may recently have removed the bug causing this.
    If this happens, remove the *first* half of records from .ratio
    and mail me, describing the operations before the discovery
    of the problem.

    Vector can handle filenames with spaces in them; however, it
    (or more accurately Move) cannot deal with wildcard characters
    in filenames, namely the following: # ? * ~ | ( ) [ ] { }
    However, these characters in filenames are quite rare, so this
    should not be a problem.

    If the same user downloads the same file on the same day several
    times in a row, Vector will get confused and keep deducting
    credits, once every check, until somebody else downloads
    something.  This unlikely situation happens exactly once in my
    6500-line xpr.log.

    If the file specified in .lastcheck cannot be found xpr.log,
    Vector dl will report "Corrupted xpr.log" and fix .lastcheck to
    point to the latest transfer.